⚡︎ memorybolt/

├── __init__.py [CORE]
├── config.yaml [CORE] # routing, engines, quotas, presets

├── memory_core.py [CORE] # engine router; failover; quotas; feature flags ⚔

├── engines/
 ├── base_engine.py [CORE] # ABC: batch, TTL/upsert hooks, lifecycle, describe(), errors ⚔
 ├── local_only_engine.py [CORE] # in-mem + optional disk spill; offline-first; zero deps ⚔
 ├── plugin_loader.py [CORE] # dynamic discovery; compat checks ⚔
 ├── redis_engine.py [ADD-ON]# TTL/pubsub; hot cache ⚔
 ├── postgres_engine.py [ADD-ON]# ACID, FTS, structured filters ⚔
 ├── vector_engine.py [ADD-ON]# FAISS/Qdrant/PGVector pluggable ⚔
 ├── semantic_engine.py [ADD-ON]# hybrid vector + rerank (multi-field) ⚔
 ├── s3_engine.py [ADD-ON]# big-blob spill; presigned URLs ⚔
 ├── geo_shard_engine.py [ADD-ON]# region routing + cost graph 🧭⚔
  └── # ROADMAP[SSSP-Upgrade]: _shortest_path_router(algo=auto|dijkstra|improved_sssp)
│ # note: ALL engines implement describe() → exposed via `mbctl describe`

├── models/
 ├── memory_object.py [CORE] # schema-lite; tags/metadata
 ├── agent_tag_schema.py [CORE] # org/agent/tenant; RBAC anchors ⚔
 ├── behavior_model.py [ADD-ON]
 ├── feedback_model.py [ADD-ON]
 ├── memory_diff.py [ADD-ON]
 ├── memory_trace.py [ADD-ON]# provenance (compliance) ⚔
 ├── snapshot.py [ADD-ON]# point-in-time restore ⚔
 └── federation_model.py [ADD-ON]# multi-engine planner (cost graph) 🧭⚔
 └── # ROADMAP[SSSP-Upgrade]: plan_route(algo=auto|dijkstra|improved_sssp)

├── api/
 ├── memory_api.py [CORE] # CRUD/query; batch; TTL
 ├── agent_memory.py [CORE] # per-agent/tenant scopes ⚔
 ├── doc_api.py [CORE] # docs in/out; chunk hooks
 ├── compliance_api.py [ADD-ON]# DSAR/Audit endpoints ⚔
 ├── plugin_api.py [ADD-ON]
 ├── model_api.py [ADD-ON]# safe uploads; manifests; stream/chunk; pre-fail warn ⚔
 └── rag_api.py [ADD-ON]

├── rag_addon/ [ADD-ON]# memorybolt-rag
 ├── rag_pipeline.py
 ├── retriever.py # hybrid (vector+semantic) ⚔
 ├── chunker.py
 ├── embedder.py # BYO embedder (local/OpenRouter) ⚔
 ├── rag_cli.py
 ├── rag_api.py
 └── rag_docs.md

├── utils/
 ├── compressor.py [CORE] # LZ4/Zstd hooks; size budgets
 ├── tokenizer.py [CORE] # local tokenizer; no giant deps ⚔
 ├── permissions.py [CORE] # RBAC/tenant/agent ⚔
 ├── healthcheck.py [CORE] # standard health + self-heal hooks
 ├── quota.py [CORE] # per-tenant rate/space/compute ⚔
 ├── deduper.py [ADD-ON]
 ├── canary_memories.py [ADD-ON]# tamper canaries ⚔
 └── archiver.py [ADD-ON]# cold storage rotation

├── resource_manager/ [ADD-ON]# memorybolt-resource ⚔
 ├── disk_manager.py # disk quotas; compaction; auto-clean
 ├── bandwidth_manager.py # throttle; off-peak sync; cost caps
 ├── cpu_manager.py # per-agent CPU ceilings; queues
 ├── gpu_manager.py # explicit-only; prevent accidental GPU burn
 ├── thread_fd_manager.py # FD/socket/thread tracking; leak kill
 ├── memfrag_manager.py # fragmentation scan; restart/compact suggest
 ├── cache_manager.py # LRU caps per module/agent
 ├── backup_manager.py # snapshots; retention; DR
 └── resource_heatmap.py # live dashboard

├── upload_manager/ [ADD-ON]# memorybolt-upload ⚔
 ├── model_upload.py # chunked/resumable; pre-quota check; OOM-proof
 ├── artifact_upload.py # large artifact pipeline
 └── resume_upload.py # checkpoint/retry

├── observability/
 ├── metrics.py [CORE] # Prom-style metrics; engine IDs ⚔
 ├── tracing.py [ADD-ON]# OpenTelemetry ⚔
 ├── memory_log_stream.py [ADD-ON]# live tail (PII-safe) ⚔
 ├── benchmark_report.py [ADD-ON]# perf vs hosted competitors ⚔
 ├── resource_alerts.py [ADD-ON]
 └── upload_alerts.py [ADD-ON]

├── events/ [ADD-ON]
 ├── event_listener.py
 └── memory_watcher.py # pattern alerts (leak/abuse) ⚔

├── filters/ [ADD-ON]
 ├── memory_filter.py
 ├── pii_cleaner.py # PII scrub; region rules ⚔
 ├── adversarial_detector.py # prompt-injection detector ⚔
 └── red_team_sim.py # red team sim ⚔

├── encryption/ [ADD-ON]
 ├── zk_vault.py # zero-knowledge/secret fields; sealed payloads ⚔
 ├── field_crypto.py # per-field AEAD/GCM ⚔
 └── memory_object_encoder.py

├── optimizer/ [ADD-ON]
 ├── ml_memory_optimizer.py
 ├── summarizer_agent.py
 ├── decay_curve.py
 ├── drift_detector.py
 └── feedback_loop.py

├── scoring/
 └── memory_ranker.py [ADD-ON]# BM25 + semantic fused rank ⚔

├── skills/ [ADD-ON]# ops/DX skills ⚔
 ├── skill_summarizer.py
 ├── skill_forgetter.py
 ├── skill_memory_tagger.py
 ├── skill_cleaner.py
 └── skill_deduper.py

├── sandbox/ [ADD-ON]
 ├── benchmark_runner.py # latency/$ vs hosted ⚔
 ├── test_vectors.json
 ├── chaos_monkey.py # failure injection
 └── adversarial_sim.py

├── seeds/ [ADD-ON]
 └── agent_seed_memory.yaml

├── configs/
 ├── memory_types_schema.yaml [CORE]
 ├── plugin_backends.yaml [CORE]
 ├── storage_policy.yaml [ADD-ON]# tiers/retention/routing 🧭⚔
  └── routing:
  strategy: shortest_path # nearest|weighted|shortest_path
 │ strategy_options:
 │ algo: auto # auto|dijkstra|improved_sssp 🧭
 │ weight_model: latency_ms # latency_ms|egress_cost|composite
 └── federation_policy.yaml [ADD-ON]# cross-engine planning 🧭⚔

├── cli/
 ├── mbctl.py [CORE] # (was fractalctl.py) enable/disable; health; describe ⚔
 ├── plugins.py [CORE]
 ├── healthcheck_cli.py [CORE]
 ├── enable_disable.py [CORE]
 ├── prune.py [CORE] # auto-slim unused extras
 ├── model_upload_cli.py [ADD-ON]
 ├── rag_cli.py [ADD-ON]
 ├── migrate.py [ADD-ON]# memU/Mem0 → MB ⚔
 ├── federate.py [ADD-ON]# multi-engine exec 🧭
 ├── archiver_cli.py [ADD-ON]
 ├── disk_clean.py [ADD-ON]
 ├── resource_leaks.py [ADD-ON]
 ├── cost_audit.py [ADD-ON]# token/$ audit ⚔
 └── heatmap.py [ADD-ON]

└── docs/
├── quickstart.md [CORE]
├── ultra_minimal.md [CORE] # zero-dep local_only path ⚔
├── modular_install.md [CORE] # engines as plugins ⚔
├── SAFE_DEFAULTS.md [CORE] # quotas + upload chunk (16MB) + CPU caps + sane retry
├── compat_matrix.md [CORE] # Python versions & optional deps per OS
├── scaling.md [ADD-ON]# routing at scale + SSSP drop-in 🧭
├── rag_docs.md [ADD-ON]
├── federation.md [ADD-ON]# cost graphs & planning 🧭
├── compliance.md [ADD-ON]# DSAR/scope/PII ⚔
├── resource_ops.md [ADD-ON]# SLO, alerts, budgets ⚔
├── model_upload.md [ADD-ON]
├── plugin_dev.md [ADD-ON]# engine SDK contract ⚔
└── migration.md [ADD-ON]# adapters & memU/Mem0 import ⚔